home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / C Internet Config / Examples ƒ / Example / IC Resource ƒ / Syslog Component ƒ / syslog.man < prev    next >
Encoding:
Text File  |  1995-11-09  |  8.9 KB  |  195 lines  |  [TEXT/R*ch]
  1.  syslog(3C)                                                       syslog(3C)
  2.  
  3.  NAME
  4.       syslog(), openlog(), closelog(), setlogmask() - control system log
  5.  
  6.  SYNOPSIS
  7.       #include <syslog.h>
  8.  
  9.       int syslog(int priority, const char *message, int parameters, ...);
  10.  
  11.       int openlog(const char *ident, int logopt, int facility);
  12.  
  13.       int closelog(void);
  14.  
  15.       int setlogmask(int maskpri);
  16.  
  17.  DESCRIPTION
  18.       syslog()       writes a message onto the system log maintained by
  19.                      syslogd (see syslogd(1M)).  The message is tagged with
  20.                      priority.  The message is similar to a printf(3S)
  21.                      format string except that %m is replaced by the error
  22.                      message associated with the current value of errno.  A
  23.                      trailing newline is added if needed.
  24.  
  25.                      This message is read by syslogd and written to the
  26.                      system console, log files, selected users' terminals,
  27.                      or forwarded to syslogd on another host as appropriate.
  28.  
  29.                      priority is encoded as the logical OR of a level and a
  30.                      facility.  The level signifies the urgency of the
  31.                      message, and facility signifies the subsystem
  32.                      generating the message.  facility can be encoded
  33.                      explicitly in priority, or a default facility can be
  34.                      set with openlog() (see below).
  35.  
  36.                      level is selected from an ordered list:
  37.  
  38.                           LOG_EMERG           A panic condition.  This is
  39.                                               normally broadcast to all
  40.                                               users.
  41.  
  42.                           LOG_ALERT           A condition that should be
  43.                                               corrected immediately, such as
  44.                                               a corrupted system database.
  45.  
  46.                           LOG_CRIT            Critical conditions, such as
  47.                                               hard device errors.
  48.  
  49.                           LOG_ERR             Errors.
  50.  
  51.                           LOG_WARNING         Warning messages.
  52.  
  53.                           LOG_NOTICE          Conditions that are not error
  54.                                               conditions, but should
  55.                                               possibly be handled specially.
  56.  
  57.                           LOG_INFO            Informational messages.
  58.  
  59.                           LOG_DEBUG           Messages that contain
  60.                                               information normally of use
  61.                                               only when debugging a program.
  62.  
  63.                      syslog() does not log a message that does not have a
  64.                      level set.
  65.  
  66.                      If syslog() cannot pass the message to syslogd, it
  67.                      attempts to write the message on /dev/console if the
  68.                      LOG_CONS option is set (see below).
  69.  
  70.       openlog()      can be called to initialize the log file, if special
  71.                      processing is needed.  ident is a string that precedes
  72.                      every message.  logopt is a mask of bits, logically
  73.                      OR'ed together, indicating logging options.  The values
  74.                      for logopt are:
  75.  
  76.                           LOG_PID             Log the process ID with each
  77.                                               message; useful for
  78.                                               identifying instantiations of
  79.                                               daemons.
  80.  
  81.                           LOG_CONS            Force writing messages to the
  82.                                               console if unable to send it
  83.                                               to syslogd.  This option is
  84.                                               safe to use in daemon
  85.                                               processes that have no
  86.                                               controlling terminal because
  87.                                               syslog() forks before opening
  88.                                               the console.
  89.  
  90.                           LOG_NDELAY          Open the connection to syslogd
  91.                                               immediately.  Normally, the
  92.                                               open is delayed until the
  93.                                               first message is logged.  This
  94.                                               is useful for programs that
  95.                                               need to manage the order in
  96.                                               which file descriptors are
  97.                                               allocated.
  98.  
  99.                           LOG_NOWAIT          Do not wait for children
  100.                                               forked to log messages on the
  101.                                               console.  This option should
  102.                                               be used by processes that
  103.                                               enable notification of child
  104.                                               termination via SIGCLD,
  105.                                               because syslog() might
  106.                                               otherwise block, waiting for a
  107.                                               child whose exit status has
  108.                                               already been collected.
  109.  
  110.                      facility encodes a default facility to be assigned to
  111.                      all messages written subsequently by syslog() with no
  112.                      explicit facility encoded.
  113.  
  114.  
  115.  
  116.                           LOG_KERN            Messages generated by the
  117.                                               kernel.  These cannot be
  118.                                               generated by any user
  119.                                               processes.
  120.  
  121.                           LOG_USER            Messages generated by random
  122.                                               user processes.  This is the
  123.                                               default facility identifier if
  124.                                               none is specified.
  125.  
  126.                           LOG_MAIL            The mail system.
  127.  
  128.                           LOG_DAEMON          System daemons, such as
  129.                                               inetd(1M), ftpd(1M), etc.
  130.  
  131.                           LOG_AUTH            The authorization system:
  132.                                               login(1), su(1), getty(1M),
  133.                                               etc.
  134.  
  135.                           LOG_LPR             The line printer spooling
  136.                                               system: lp(1), lpsched(1M),
  137.                                               etc.
  138.  
  139.                           LOG_LOCAL0          Reserved for local use.
  140.                                               Similarly for LOG_LOCAL1
  141.                                               through LOG_LOCAL7.
  142.  
  143.       closelog()     closes the log file.
  144.  
  145.       setlogmask()   sets the log priority mask to maskpri and returns the
  146.                      previous mask.  Calls to syslog() with a priority not
  147.                      set in maskpri are rejected.  The mask for an
  148.                      individual priority pri is calculated by the macro
  149.                      LOG_MASK(pri); the mask for all priorities up to and
  150.                      including toppri is given by the macro
  151.                      LOG_UPTO(toppri).  By default, all priorities are
  152.                      logged.
  153.  
  154.  RETURN VALUE
  155.       syslog() returns zero if it is successful in writing to the system log
  156.       or if priority is masked out.  It returns -1 if it is unable to write
  157.       to the system log or if priority is out of range.
  158.  
  159.  EXAMPLES
  160.       who logs a message regarding some sort of unexpected and serious
  161.       error:
  162.  
  163.            syslog(LOG_ALERT, "who: internal error 23");
  164.  
  165.       ftpd uses openlog() to arrange to log its process ID, to log to the
  166.       console if necessary, and to log in the name of the daemon facility:
  167.  
  168.            openlog("ftpd", LOG_PID|LOG_CONS, LOG_DAEMON);
  169.  
  170.       Arrange to log messages only at levels LOG_ERR and lower:
  171.  
  172.            setlogmask(LOG_UPTO(LOG_ERR));
  173.  
  174.       Typical usage of syslog() to log a connection:
  175.  
  176.            syslog(LOG_INFO, "Connection from host %d", CallingHost);
  177.  
  178.       If the facility has not been set with openlog(), it defaults to
  179.       LOG_USER.
  180.  
  181.       Explicitly set the facility for this message:
  182.  
  183.            syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m");
  184.  
  185.  WARNINGS
  186.       A call to syslog() has no effect unless the syslog daemon
  187.       (syslogd(1M)) is running.  openlog() does not copy and store the ident
  188.       string internally; it stores only a character pointer.  Therefore it
  189.       is the responsibility of the programmer to make sure that the ident
  190.       argument points to the correct string until the log file is closed.
  191.  
  192.  AUTHOR
  193.       syslog() was developed by the University of California, Berkeley.
  194.  
  195.